'\" t
'
' Name:		tpfix.1m
'
' Completed:	29th August, 2003.
'
' Updated:	
'
' Purpose:	Describes the tpfix command.
'
' Author:	Simon Edwards, Proprius Consulting Ltd.
'
' Version:	@(#)1.1 Original (SE)
'
.TH tpremove 1M "29 August 2003" "Linuxha.net"

.SH NAME
tpfix - List or fix broken packages

.SH SYNOPSYS
.TS
l l.
tpfix \fB-l\fP [\fB-v\fP] ...	List broken packages

tpfix \fB-P\fP \fB-p\fP \fIpkg\fP [\fB-v\fP] ...	Preview fixing broken package

tpfix \fB-p\fP \fIpkg\fP [\fB-v\fP] ...	Fix broken package
.TE

.SH DESCRIPTION

The \fItpfix(1M)\fP utility is used to tidy up aborted installations and
removals of packages. In almost all cases if use of the \fItpremove(1M)\fP
or \fItpinstall(1M)\fP fails the routine will tidy up to leave the package
in a consistent state (removed or installed/committed). However if you 
interrupt the process, (either explicitly, or by rebooting the server), 
no such tidy up is performed - even when simply using the \fBHUP\fP, \fBINT\fP,
\fBQUIT\fP or \fBTERM\fP signals.

This action is intentional - it aims to abort the current process as soon
as possible - allowing the user to resolve the situation manually or even
automatically on a system reboot.

.SH DEFINING THE PACKAGE STATUS

As the \fItpintro(1M)\fP page discusses there are several known, good states
that a package may be in when installed "correctly". During the installation
and removal of packages the status will deviate from one of these known states
to ensure that an accurate account of the current status is maintained.

Through out the process of package installation or removal the utilities
aim to ensure that a clean-up operation can be completed at any time to leave
a package in a consistent state with as little work as possible.

When running the utility in "list" mode, (see arguments below), the command
given a description of the status of the package which may help the user
to determine the likely state of a given package.

Each of these package states will now be explained.

.TP 8
.B Killed during final tpfix cleanup
The actually process of doing the final clean-up for a package was
interrupted. This can occasionally happen if the tpfix itself is killed off.

Running \fItpfix(1M)\fP itself again against this package will actually 
remove it! The package files will have all been removed, the only trace of
the package will be the Installed Package Database itself.

.TP
.B Partial package installation detected
This occurs if during the package installation the process of copying the
files to install to their final destination becomes interrupted.

In this instance some of the files for the package will have actually been
installed. The recovery actions in this case are to remove the files that
have already been installed and reinstall any files that this package
intended to over-write.

After running against a package in this state the package will have been 
completely removing from the system.

.TP
.B Contents to overwrite not saved
This occurs if a package installed is aborted at the very first stage - it 
has created a temporary directory in the Installed Package Database directory
but not actually installed any files elsewhere in the file system.

The clean-up actions simply require this directory to be removed.

.TP
.B Overwritten files not 100% saved
This occurs if a package installed is aborted early during the installation
process. Before any files are actually installed it will check to see if any
files will be over-written, and if so will back them up.

This problem indicates that this process had not yet completed. The clean-up
consists of simply removing the back-up information, and then the package
information from the Installed Package Database directory.

.TP
.B Missing installation contents
This is a rare occurance and happens when the package to install has not yet
even started being spooled from the depot to the Installed Package Database
area. It basically means that the installation was aborted or ran out of space
just after creating a temporary directory.

The recovery action is to simply remove the temporary directory. Note that
in the list output the name of the package will be in the format "tpinstall-NN"
because at this point the name of the package that was being installed is not
even recorded!

.TP
.B Backup of removed files not complete
This can occur if a package removal is aborted or runs out of disk space. 
Before the command actually removes the files it will back them up to a 
temporary area. This status indicates that this process did not complete.

Since at this point no files have actually been removed from the package
the recovery action is to delete this backed-up files and then restore the
original status of the package to "Installed" or "Committed" as appropriate.

.TP
.B Partial remove of installed files
This indicates that the removal of a package was aborting during the actual
process of removing the files that the package provided.

The recovery action in this instance is to restore the files that have been
removed so far. The package will then be left in a valid "Installed" or
"Committed" as appropriate.

.TP
.B Partial restore of overwritten files
This status can only occur if you interrupt a removal of a package which was
originally in the "Installed" state compared to the more usual "Committed"
state.

The status indicates that although the package has been removed successfully
it did not restore all the files that were originally overwritten when the 
package was installed.

The \fItpfix(1M)\fP utility when run against a package in this status
would actually restore the package to its original "Installed" status,
basically by doing a complete re-installation of the files involved in the
package. 
.RS

.SH ARGUMENTS
The following arguments are supported by the utility - all are optional
unless otherwise stated.

.TP 4
.B -p
Mandatory argument that should be followed by the name of the package
you wish to fix. If the specified package is not currently in a broken
status an error will be given.
.TP
.B -P
Preview mode - show information about what steps the utility would take to
rectify a failed package installation or removal, but do not actually 
perform these steps.
.TP
.B -l
List mode - produce a list of packages that are currently thought to be 
borken, along with information regarding whether they broke during installation
or removal, and the current package status.
.TP
.B -v
Verbose mode - show copious progress messages to the standard output
devices. Without this you will only see warnings (to standard output) and
errors (to standard error).

.SH EXAMPLES
.SS Example 1 - Checking the configuration
The first example checks to see if there are any packages in are 
percieved to be broken, querying the users own Installed package database 
in $HOME/tarp.

.TS
l.
$ TARP_DB=$HOME/tarp; export TARP_DB
$ tplist
.TE

This may produce output similar to the following:

.TS
l.
Package      Version Status    Description
============ ======= ========= ============================
functions    1.02.00 Committed Generic functions 
healthcheck  1.01.00 Removing2 Healthcheck utility 
.TE

The above output shows an "intermediate" state for the "healthcheck"
package. This is now confirmed by using \fItpfix(1M)\fP in the
mode to list broken packages:

.TS
l.
$ tpfix -l
.TE

In this instance the output generated confirms the problem:

.TS
l.
Package       Broken    Reason
============= ========  ========================================
healthcheck   Remove    Partial remove of installed files
.TE

.SS Example 2 - Previewing fixing a Broken Package
Now that the problem has been confirmed with the package the user can
preview the actions taken by running the following command:

.TS
l.
$ tpfix -P -p healthcheck -v
.TE

In this instance the output generated is as follows:

.TS
l.
MSG  : Scanning Installed Package database ...
MSG  : Broken packages found: 1
MSG  : Scanning for package instance healthcheck ...
MSG  : Status of broken installation for healthcheck
MSG  : 
MSG  : Package       Broken    Reason
MSG  : ============= ========  ===================================
MSG  : healthcheck   Remove    Partial remove of installed files
MSG  : 
MSG  : Restoring partially removed package ...
MSG  : Removing partially saved files ...
MSG  : Resetting Package status ...
MSG  : Package status reverted to Committed
.TE

This preview run has told us that after the package is fixed it will be
left as an installed package rather than be removed.

.SS Example 3 - Fixing a Broken Package
Finally we attempt to fix the broken package by running the same command
as above, but without the "-P" option (preview):

.TS
l.
$ tpfix -p healthcheck -v
.TE

This will output the following details:

.TS
l.
MSG  : Scanning Installed Package database ...
MSG  : Broken packages found: 1
MSG  : Scanning for package instance healthcheck ...
MSG  : Status of broken installation for healthcheck
MSG  : 
MSG  : Package       Broken    Reason
MSG  : ============  ========  ===================================
MSG  : healthcheck   Remove    Partial remove of installed files
MSG  : 
MSG  : Restoring partially removed package ...
MSG  : Restored 184 files
MSG  : Removing partially saved files ...
MSG  : Resetting Package status ...
MSG  : Package status reverted to Committed
.TE

Notice that now the number of files restored is given. The restoration of the
package can take some time, but once completed we can check the status again:

.TS
l.
$ tplist -l 
.TE

In this case the output is as expected:

.TS
l.
Package         Version  Status    Description
=============== ======== ========= ============================
functions       1.02.00  Committed Generic functions 
healthcheck     1.01.00  Committed Healthcheck utility 
.TE

.SH EXIT CODES
The utility makes extensive use of exit codes, you are encourgaged to check
the return code if an error occurs and refer to the following values.

.TP 4
.B 0
The specified operation has completed successfully. This could be listing
broken packages, previewing a fix or actually performing a fix.
.TP
.B 1
Invalid command line arguments have been specified - a usage message will
have been shown on standard errror.
.TP
.B 2
The Installed Package Database specified does not appear to exist, (either
/var/adm/tarpdb or the directory given by the \fBTARP_DB\fP environment
variable).
.TP
.B 3
The utility was unable to read the contents of the Installed Package Database.
.TP
.B 4
The package specified to fix does not appear to exist at all, or exist in a
broken status.
.TP
.B 5
The fix routine was unable to remove a temporary directory in the Installed
Package Database - do you have permissions to alter this directory structure?
.TP
.B 6
Unable to rename a directory in the Installed Package Database directory - do 
you have the required permissions to alter this directory structure?
.TP
.B 7
The \fItpfix(1M)\fP command was unable to change the status of the
specified package. Either the containing file system is full, or you do not
have the required permissions.
.TP
.B 8
The specified files archived as part of a package removal can not be found -
usually indicates that someone has manually attempted to clear up the
package status by removing the specified temporary directory by hand.
.TP
.B 9
This is a similar problem to the error above and is most likely caused by
someone manually removing files from the Installed Package Database directory
structure. See the \fBWARNINGS\fP section below for further details.
.TP
.B 10
The directory used for the Installed Package Database did not exist, and the
utility was unable to create it.
.TP
.B 11
The utility failed to restore one or more files which were needed to re-instate
a partially removed package. This is typically caused by lack of permissions
or storage space in a destination directory.
.TP
.B 12
A permissions error has occured when trying to change directory into the
directory containing details of the broken package.

.SH FILES
All information required for this utility to run are found in the 
directory structure /var/adm/tarpdb, or wherever the \fBTARP_DB\fP
environment variable points to.

.SH WARNINGS
It is important that no manual changes are made to a directory structure
acting as the Installed Package Database. If the \fItpfix(1M)\fP is unable to
resolve the problem then try logging a problem on the project's support
page.

.SH SEE ALSO
.BR tpintro(1M),
.BR tpinstall(1M),
.BR tppkg(1M),
.BR tplist(1M),
.BR tpchk(1M).

.SH WARRANTY/LICENSE/ENVIRONMENT
This utility is available under the GNU GPL, and comes with 
\fIno warranty or guarantee of any kind\fP.

This program is only suitable for environments that have the following
software components installed:

.TP 4
.B Shell Utilities
The following utilities are required, \fIawk(1)\fP, \fIksh(1)\fP
as well as the standard utiltiies to check, move and remove files and 
directories.
.TP
.B Perl
Any version of Perl from 4 onwards with standard installation libraries
should be suitable. Currently Perl is only used spareingly, but still must
be available.

